home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / Vk / VkRunOnce.z / VkRunOnce
Encoding:
Text File  |  2002-10-03  |  9.6 KB  |  265 lines
  1.  
  2.  
  3.  
  4. VVVVkkkkRRRRuuuunnnnOOOOnnnncccceeee((((3333xxxx))))                                                    VVVVkkkkRRRRuuuunnnnOOOOnnnncccceeee((((3333xxxx))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      VkRunOnce - Allow an application to have only a single instance
  10.  
  11. IIIINNNNHHHHEEEERRRRIIIITTTTSSSS FFFFRRRROOOOMMMM
  12.      VkComponent : VkCallbackObject
  13.  
  14. HHHHEEEEAAAADDDDEEEERRRR FFFFIIIILLLLEEEE
  15.      #include <Vk/VkRunOnce.h>
  16.  
  17.  
  18. PPPPUUUUBBBBLLLLIIIICCCC PPPPRRRROOOOTTTTOOOOCCCCOOOOLLLL SSSSUUUUMMMMMMMMAAAARRRRYYYY
  19.    CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrr////DDDDeeeessssttttrrrruuuuccccttttoooorrrr
  20.            VkRunOnce(VkNameList *args, Boolean per_host);
  21.            ~VkRunOnce();
  22.  
  23.  
  24.    RRRReeeettttrrrriiiieeeevvvviiiinnnngggg AAAArrrrgggguuuummmmeeeennnnttttssss
  25.            int numArgs();
  26.            char *arg(int index);
  27.  
  28.  
  29.    CCCCaaaallllllllbbbbaaaacccckkkkssss
  30.            const char *const invokedCallback;
  31.  
  32.  
  33. CCCCLLLLAAAASSSSSSSS DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  34.      This class is subtly different from VkRunOnce2.  Both classes should be
  35.      understood before deciding which to use.
  36.  
  37.      This class allows applications to specify that only a single instance of
  38.      the application can be run on any system at any one time. This is useful
  39.      when implementing applications that are meant to provide a system-wide
  40.      service for multiple applications. For example, an audio control program
  41.      that controls the volume an other parameters on a system should not
  42.      normally need to have multiple instantiations. However, various programs
  43.      or scripts might wish to launch the application, and have no way to know
  44.      if the program is already running.
  45.  
  46.      Using VkRunOnce, such programs can simply be run as many times as
  47.      desired.  Only the first run will actually display the program.
  48.      Subsequent runs will notify the running instance, possibly passing some
  49.      arguments. The running instance will raise itself, and respond to any
  50.      arguments provided. The second instance of the application will simply
  51.      exit.
  52.  
  53. FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNNSSSS
  54.    VVVVkkkkRRRRuuuunnnnOOOOnnnncccceeee
  55.             VkRunOnce(VkNameList *args,
  56.                        Boolean per_host);
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. VVVVkkkkRRRRuuuunnnnOOOOnnnncccceeee((((3333xxxx))))                                                    VVVVkkkkRRRRuuuunnnnOOOOnnnncccceeee((((3333xxxx))))
  71.  
  72.  
  73.  
  74.           Initialize a VkRunOnce object. If this is the only current instance
  75.           of this program running on the system, this constructor establishes
  76.           this application as the sole runnable instance. Normally, "running
  77.           on this system" is defined to mean an application whose X DISPLAY is
  78.           set to the current display device. If per_host is TRUE, multiple
  79.           instances are allowed on any given display, so long as each instance
  80.           is running on a different host.
  81.  
  82.           If this is the second time an application is run, the VkRunOnce
  83.           constructor makes contact with the running instance, passing it any
  84.           arguments supplied in the args parameter. The constructor then
  85.           causes the application to exit by calling VkApp::terminate().
  86.  
  87.    ~~~~VVVVkkkkRRRRuuuunnnnOOOOnnnncccceeee
  88.               ~VkRunOnce();
  89.  
  90.  
  91.           If the VkRunOnce object is deleted, and this application is the
  92.           current single instance of this application, multiple instances of
  93.           this program are then allowed to run.
  94.  
  95.    ccccllllaaaassssssssNNNNaaaammmmeeee
  96.               virtual const char* className();
  97.  
  98.  
  99.           The class name of this class is "VkRunOnce".
  100.  
  101. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  102.      The following program displays a string in a window. After the first
  103.      instance, subsequent instances of the program pass the first command line
  104.      argument to the running instance, to be displayed as a string in the
  105.      application's window.
  106.  
  107.  
  108.            #include <Vk/VkApp.h>
  109.            #include <Vk/VkRunOnce.h>
  110.            #include <Vk/VkNameList.h>
  111.            #include <Vk/VkSimpleWindow.h>
  112.            #include <Xm/Label.h>
  113.  
  114.            // Define a top-level window class
  115.  
  116.            class RunOnceWindow: public VkSimpleWindow {
  117.  
  118.             protected:
  119.  
  120.                Widget _label;
  121.  
  122.  
  123.             public:
  124.  
  125.               RunOnceWindow ( const char *name ) :
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. VVVVkkkkRRRRuuuunnnnOOOOnnnncccceeee((((3333xxxx))))                                                    VVVVkkkkRRRRuuuunnnnOOOOnnnncccceeee((((3333xxxx))))
  137.  
  138.  
  139.  
  140.                            VkSimpleWindow ( name )
  141.               {
  142.                    _label =  XmCreateLabel ( mainWindowWidget(),
  143.                                              "first instance",
  144.                                               NULL, 0 );
  145.  
  146.                    addView(_label);
  147.               }
  148.  
  149.               ~RunOnceWindow();
  150.  
  151.               void update(VkComponent *comp, XtPointer, XtPointer);
  152.  
  153.               virtual const char* className() {
  154.                                  return "RunOnceWindow";
  155.                               }
  156.            };
  157.  
  158.            RunOnceWindow::~RunOnceWindow()
  159.            {
  160.               // Empty
  161.            }
  162.  
  163.            void RunOnceWindow::update(VkComponent *comp,
  164.                                       void*,
  165.                                       void*)
  166.            {
  167.               // Just retrieve the arguments, Use the first string
  168.               // as a new label for the widget and the second
  169.               // as a color.
  170.  
  171.               VkRunOnce *obj = (VkRunOnce*) comp;
  172.  
  173.               if(obj->numArgs() > 0)
  174.               {
  175.                   XtVaSetValues(_label,
  176.                                 XtVaTypedArg,
  177.                                 XmNlabelString, XmRString,
  178.                                 obj->arg(0),
  179.                                 strlen(obj->arg(0) ) + 1,
  180.                                 NULL);
  181.               }
  182.            }
  183.  
  184.  
  185.            // Main driver. Instantiate a VkApp and a top-level
  186.            // window, "show" the window and then "run" the
  187.            // application. The VkRunOnce object prevents
  188.            // multiple instances of the application.
  189.  
  190.            void main ( int argc, char **argv )
  191.            {
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. VVVVkkkkRRRRuuuunnnnOOOOnnnncccceeee((((3333xxxx))))                                                    VVVVkkkkRRRRuuuunnnnOOOOnnnncccceeee((((3333xxxx))))
  203.  
  204.  
  205.  
  206.               VkApp        *app = new VkApp("RunOnce", &argc, argv);
  207.  
  208.               // Construct a VkNameList object to pass arguments
  209.               // and load the first argument, if any
  210.  
  211.               VkNameList *args = new VkNameList();
  212.  
  213.               if(argc == 2)
  214.                   args->add(argv[1]);
  215.  
  216.               VkRunOnce *runOnce = new VkRunOnce(args);
  217.  
  218.               // Create a window
  219.  
  220.               RunOnceWindow  *win = new RunOnceWindow("hello");
  221.  
  222.               // Register a callback for running applications
  223.               // to receive if anyone attempts to run this
  224.               // application again.
  225.  
  226.               VkAddCallbackMethod(VkRunOnce::invokedCallback, runOnce,
  227.                                   win, RunOnceWindow::update, NULL);
  228.  
  229.               win->show();
  230.               app->run();
  231.            }
  232.  
  233.  
  234.  
  235. IIIINNNNHHHHEEEERRRRIIIITTTTEEEEDDDD MMMMEEEEMMMMBBBBEEEERRRR FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS
  236.    IIIInnnnhhhheeeerrrriiiitttteeeedddd ffffrrrroooommmm VVVVkkkkCCCCoooommmmppppoooonnnneeeennnntttt
  237.           installDestroyHandler(), removeDestroyHandler(), widgetDestroyed(),
  238.           setDefaultResources(), getResources(), manage(), unmanage(),
  239.           baseWidget(), okToQuit(), _name, _baseWidget, _w, deleteCallback
  240.  
  241.  
  242.    IIIInnnnhhhheeeerrrriiiitttteeeedddd ffffrrrroooommmm VVVVkkkkCCCCaaaallllllllbbbbaaaacccckkkkOOOObbbbjjjjeeeecccctttt
  243.           callCallbacks(), addCallback(), removeCallback(),
  244.           removeAllCallbacks()
  245.  
  246.  
  247. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  248.      VkApp(3x), VkRunOnce2(3)
  249.      _V_i_e_w_K_i_t _P_r_o_g_r_a_m_m_e_r'_s _G_u_i_d_e
  250.      _T_h_e _X _W_i_n_d_o_w _S_y_s_t_e_m, DEC Press, Bob Sheifler and Jim Gettys
  251.      _T_h_e _X _W_i_n_d_o_w _S_y_s_t_e_m _T_o_o_l_k_i_t, DEC Press, Paul Asente and Ralph Swick
  252.      _T_h_e _O_S_F/_M_o_t_i_f _P_r_o_g_r_a_m_m_e_r_s _R_e_f_e_r_e_n_c_e, Prentice Hall, OSF
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.